docs(js): Add New Spans guide#17834
Conversation
…ick-start/splitlayout-cleanup
…ick-start/splitlayout-cleanup
… smi/span-first/js
inventarSarah
requested review from
Lms24,
chargome,
cleptric,
mydea and
sfanahata
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
![sentry-warden[bot]](https://avatars.githubusercontent.com/in/2755838?s=60&v=4){kind=small}
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit b8d6819. Configure here.
|
|
||
| <PlatformSection notSupported={["javascript.nextjs", "javascript.nuxt", "javascript.sveltekit", "javascript.astro", "javascript.solidstart", "javascript.capacitor", "javascript.tanstackstart-react", "javascript.remix", "javascript.react-router"]}> | ||
|
|
||
| - **Check the Sentry dashboard**: Spans should appear in the Traces view shortly after they complete. Traces look the same as in transaction mode, but without transactions. |
There was a problem hiding this comment.
Traces look the same as in transaction mode, but without transactions
This is true but unless I missed something, there are very few visual indications that actually point out that a span is a (new) span and not a transaction 😬 The only thing that comes to mind is that it's not showing a JSON button anymore. I don't think there's harm in leaving in this sentence but users might get confused at what they should be looking in the product.
This is of course not a primary docs issue but rather a product/UI issue. We might want to think about some kind of indicator (and, separate topic, please bring back JSON for streamed spans lol). That is assuming, I didn't miss any obvious indication 😅 Will ask product folks about this.
There was a problem hiding this comment.
In that case, I will update this to something like
"Traces look almost the same as in transaction mode. The main difference is that they have no transactions and only consist of spans."
There was a problem hiding this comment.
In the new experience, what do we call those attributes that we currently call transaction?
There was a problem hiding this comment.
@Lms24 Have you received a response from the product team yet?
There was a problem hiding this comment.
No response so far :( I suggest for now we go with the more generic sentence. If we decide to mark them specifically in the product, we can update this section. (I'm hacking on a small visual indication but no guarantees that this will get approved/merged).
There was a problem hiding this comment.
I opened getsentry/sentry#116386 which proposes a visual indication. Can't promise that this gets merged though yet. Will keep you posted!
| @@ -0,0 +1,370 @@ | |||
| --- | |||
| title: New Spans | |||
| description: "Learn how to use stream mode to send spans to Sentry as they finish, removing the 1,000-span limit and making trace data visible sooner." | |||
There was a problem hiding this comment.
@cleptric - should we be calling out the 1k span limit as a benefit? Seems really valuable, but want to make sure we're not locking ourselves into something unnecessarily.
There was a problem hiding this comment.
Don't wanna answer for Michi (so feel free to overrule me) but removing the hard 1k limit is the key feature of span streaming. I think we can/should call it out. The 1k limit exists but isn't documented publicly a lot (besides this zendesk page). I don't think it's a secret though, so no harm in mentioning it.
| - javascript.cordova | ||
| --- | ||
|
|
||
| <AvailableSince version="10.53.1" /> |
There was a problem hiding this comment.
This is SDK version? Would be good to clarify.
There was a problem hiding this comment.
Actually, let me remove that because we have the required SDK version in the Prerequisites section.
|
|
||
| ## Extended Configuration (Optional) | ||
|
|
||
| ### Filter Spans |
There was a problem hiding this comment.
I think this may be the right place for it, but somewhere on this page I believe we should mention with a slight bit more detail in the description that you also need to modify span.op to span.attributes?.["sentry.op"] and that description becomes name in this new paradigm.
There was a problem hiding this comment.
Updated this section to mention these changes in the text accompanying the code snippet. And then I referred to the "migration" note, where I've added the table with all name changes.
wdyt?
|
|
||
| </Alert> | ||
|
|
||
| ### Drop Spans |
There was a problem hiding this comment.
@Lms24 - just wanting to verify that this behavior is true:
In transaction mode, ignoreSpans is evaluated at transaction end (so all attributes accumulated during the span's lifetime are available). In stream mode, it's evaluated at span start (so only initial attributes are considered).
If so, @inventarSarah, it may be useful to add that detail or heads up here.
There was a problem hiding this comment.
Yes, you can find this down below at line 339+
It will render below the split layout section here because the info isn't relevant to the code snippet.
But let me know if you think it would make more sense, or help users avoid missing this info, if we pull it into the split layout.
There was a problem hiding this comment.
I moved the stream mode-specific explanation under the section header and left the stream mode vs transaction mode explanations in the migration callout below - wdyt?
Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
Lms24
left a comment
Lms24
left a comment
There was a problem hiding this comment.
Second pass: Just had some minor remarks, other than that this looks good to me!
Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>
4 participants
DESCRIBE YOUR PR
Adds a new page documenting stream mode for all JS SDKs, covering:
beforeSendSpan,ignoreSpans)Based on this draft: #17621
Michi's draft includes sections on distributed tracing, which I removed in this version. The APIs work identically in both modes; the topics are advanced enough that users are better served by the existing page, where all the details live, and users who already have distributed tracing set up don't need to change anything when switching to stream mode. Happy to discuss if you disagree.
Questions/Considerations for you
Closes: #17835
IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
EXTRA RESOURCES